---
title: Configuration.mux()
api: Configuration.mux
---

## Description

<Summary/>

<FilterDiagram
  name="mux"
  input="Message"
  output="Message"
  subInput="Message"
  subType="mux"
/>

A _mux_ filter does the following:

- At the input to a _mux_ filter, the _Message_ is merged to a sub-pipeline that is shared by multiple _mux_ filters
- At the input to the shared sub-pipeline, _Messages_ from multiple _mux_ filters are queued up into one single _Message_ stream
- Whatever is outputted from the shared sub-pipeline is discared
- At the output from the _mux_ filter, out come the same _Mesasge_ as its input

Multiple _mux_ filters can have one shared sub-pipeline, in which many input _Messages_ are queued up.

### Stream sharing

You can control where a _mux_ filter merges its input _Message_ to by specifying a _"merging target"_. It can be a value of any type or a function that returns it. Filters with the same _merging target_ share and merge to the same sub-pipeline.

> Merging only happens among filters coming from the same place in the same pipeline layout. Two filters from different pipeline layouts or different places in the same pipeline layout will never merge to the same sub-pipeline, even when they have the same _merging target_.

### Sub-pipeline lifecycle

Since the sub-pipeline is shared by multiple _mux_ filter instances, it won't be closed until the last _mux_ ends. After all _mux_ filter instances sharing it are done, the sub-pipeline will wait for 60 seconds to ensure no more new _mux_ filters come and merge to it. You can change this waiting time by the _maxIdle_ option in the _options_ parameter. It can be either a number in seconds or a string with a unit suffix such as `'s'`, `'m'`, `'h'`, `'d'`.

> When the _merging target_ is an object, it will be a _weak ref_, just like a key in a [WeakMap](https://developer.mozilla.org/docs/Web/JavaScript/Guide/Keyed_collections#weakmap_object). When the object is dead, so is the sub-pipeline being weakly referenced by the object, regardless of the _idleTime_ option.

## Syntax

``` js
pipy()
  .pipeline()
  .mux().to(
    subPipelineLayout
  )

pipy()
  .pipeline()
  .mux(
    () => whereToMerge()
  ).to(
    subPipelineLayout
  )

pipy()
  .pipeline()
  .mux({
    maxIdle,
    maxQueue,
  }).to(
    subPipelineLayout
  )

pipy()
  .pipeline()
  .mux(
    () => whereToMerge(),
    {
      maxIdle,
      maxQueue,
    }
  ).to(
    subPipelineLayout
  )
```

## Parameters

<Parameters/>

## See Also

* [Configuration](/reference/api/Configuration)
* [demux()](/reference/api/Configuration/demux)
* [demuxQueue()](/reference/api/Configuration/demuxQueue)
* [demuxHTTP()](/reference/api/Configuration/demuxHTTP)
* [muxQueue()](/reference/api/Configuration/muxQueue)
* [muxHTTP()](/reference/api/Configuration/muxHTTP)
* [serveHTTP()](/reference/api/Configuration/serveHTTP)
